Device Nominations (C/C++)
| |
Nomination Routine |
Description of device |
| A |
gWogl(hInst,hPrevInst) |
Opens a default window |
| B |
gWoglw(hInst,hPrevInst,x,y,width,height) |
Opens a window at the specified position and size |
| C |
gWoglao(hInst,hPrevInst,hWnd,hDC) |
Opens GINO using an existing bitmap |
| D |
gWogldc(hInst,hPrevInst,hWnd,hDC) |
Opens GINO with a private bitmap |
| E |
gWoglp (hInst,hPrevInst) |
Opens a Windows printer for GINO output |
| F |
gWogldp (hInst,hPrevInst) |
Opens the default Windows printer for GINO output |
| G |
status=gWoglpp(hInst, hPrevInst, mode, devname, dlen, filename, flen, n, prop) |
Printing and Setup control for Windows printers |
| H |
status=gWoglm(hInst,hPrevInst,type,dpi,xres,yres, ...) |
Opens metafile for OpenGL output |
| I |
gOglwin() |
OpenGL graphics frame(s) in GINOMENU |
Device Nominations (F90/Delphi/VB/.NET)
| |
Nomination Routine |
Description of device |
| A |
gWogl |
Opens a default window |
| B |
gWoglw(x,y,width,height) |
Opens a window at the specified position and size |
| C |
gWoglao(hWnd,hDC) |
Opens GINO using an existing bitmap |
| D |
gWogldc(hWnd,hDC) |
Opens GINO with a private bitmap |
| E |
gWoglp |
Opens a Windows printer for GINO output |
| F |
gWogldp |
Opens the default Windows printer for GINO output |
| G |
status=gWoglpp(mode,devname,filename,n,prop) |
Printing and Setup control for Windows printers |
| H |
status=gWoglm(type,dpi,xres,yres,gFilename,gQuality) |
Opens metafile for OpenGL output |
| I |
gOglwin |
OpenGL graphics in GINOMENU |
Device Characteristics
| Default Width (of max) |
3/4 |
variable |
variable |
variable |
Maximum |
Maximum |
Maximum |
variable |
variable |
| Default Height (of max) |
3/4 |
variable |
variable |
variable |
Maximum |
Maximum |
Maximum |
variable |
variable |
| Image Handling (output, input, copy) |
Yes |
Yes |
Yes |
Yes |
Printer Dependent |
Printer Dependent |
Printer Dependents |
Yes |
Yes4 |
| Cursor Types* |
Yes1 |
Yes1 |
Yes1 |
Yes1 |
No |
No |
No |
No |
Yes1 |
| Cursor Actions* |
Yes2 |
Yes2 |
Yes2 |
Yes2 |
No |
No |
No |
No |
Yes2 |
| Event Types* |
Yes3 |
Yes3 |
Yes3 |
Yes3 |
No |
No |
No |
No |
No |
| Batch Updates* |
Yes |
Yes |
Yes |
Yes |
No |
No |
No |
Yes |
Yes |
| Auxiliary Drawing Areas (up to 250 pairs) |
Yes |
Yes |
Yes |
Yes |
No |
No |
No |
No |
No |
| Window/Device Titling |
Yes |
Yes |
No |
No |
No |
No |
No |
No |
No |
| Colours / Pens |
Screen / printer dependent |
| Fonts |
As installed including 6 registered (100,101,102,150,151,170) |
| Character Sizes |
Any size (16 pseudo sizes) |
| Character Angles |
Horizontal only |
| Polygonal Filling |
Multi-polygon, solid fill, 1024 vertices |
| Clipping |
Yes (Windowing only) |
* when using the gWoglao() nomination routine, the handle to the window must be provided for these features to be available
Yes1 GDEFAULT, GSMALLCROSS, GMEDIUMCROSS, GLARGECROSS, GCROSSHAIR, GX, GLARGEX, GPOINTER, GHOURGLASS, GEXIT (Colour control only on GLARGECROSS/GCROSSHAIR)
Yes2 GPOLYLINE, GRUBBERBAND GRUBBERBOX, GRUBBERSQUARE, GRUBBERELLIPSE, GRUBBERCIRCLE
Yes3 GKEYPRESS, GLOCATOR, GMOVEMENT, GKEYRELEASE, GRESIZE, GMOUSEWHEEL
Driver Availability
The Wogl series of drivers are used for OpenGL graphics output to the screen, metafile or printer under Windows.
Device Nomination & Usage
The Windows OpenGL driver operates under any of the Microsoft Windows environments (Windows 95,98, NT and 2000) using a combination of the Windows API and the OpenGL API to provide a fully functional 3D GINO driver. The driver requires access to OPENGL32.DLL and GLU32.DLL.
Many of the features provided by this driver are the same as the standard Windows driver to which several sections below will refer.
When using the C routines, all except gOglwin() require the handle to the current instance of the program (hInst) and, if available, the handle to the previous instance (hPrevInst) to be passed to the nomination routine as the first two parameters. In a C program these parameters are available in the WinMain() procedure. The nomination routines are described below:
gWogl
This nomination routine opens a standard window of 3/4 screen size at a default position. The device driver will only update the screen upon a call to gFlushGraphics() / gCloseDevice() / gSuspendDevice(), before cursor or event routines are called, or upon a Windows paint event. The following examples show the nomination routine in the context of a program:
[C/C++]
#include <windows.h>
#include <gino-c.h>
int PASCAL WinMain(HANDLE hInst, HANDLE hPrevInst,
LPSTR lpszCmdParam, int nCmdShow)
{
/* Nominate the device */
gWogl(hInst, hPrevInst);
/* Use GINO routines here */
/* Close the device */
gCloseDevice();
}
[F90]
Program Main
use gino_f90
! Nominate the device
call gWogl
! use GINO routines here
.
! Close the device
call gCloseDevice
Stop
End
gWoglw
gWoglw() is essentially the same as gWogl(), however the size & position of the window can be specified. x, y is the pixel position of the top left corner of the window (coordinate (0, 0) is the top left of the screen) and width, height are the width and the height of the required window in pixels. If width or height are less than or equal to zero the default size is used. If the requested size is larger than the screen then the size is automatically set to the same size as the screen.
gWoglao
This nomination routine allows for greater flexibility, but at the loss of some ease of use. Existing windows and device contexts can be used for output enabling GINO to send its output to other applications, however a device context should always contain a valid bitmap. Usage of this routine in F90, C and Visual Basic is the same as the gMwinao() routine in the standard Windows driver. (See GUI Programming).
gWogldc
The gWogldc() nomination routine is similar to gWoglao() except that GINO creates and maintains an internal private bit map of the same size as the bitmap who's handle is passed in hDC. This is most useful in environments where a new bitmap handle is continually generated for the drawing area when a resize or repaint message is generated such as .NET and Delphi. The advantage of creating a private bitmap is that any drawing previously directed to the drawing area is not lost and does not have to be regenerated as well. Usage of this routine is the same as the gMwindc() routine in the standard Windows driver. (See GUI Programming).
gWoglp
This nomination routine will use a windows printer for output. A dialog box will be displayed upon nomination allowing the user to select a printer. The form of a call to this routine is the same as a call to gWogl().
gWogldp
This nomination routine will use the default windows printer for output. The form of a call to this routine is the same a call to gWogl() or gWoglp().
Print Status Detection
A function gWoglst() is provided with this driver to detect the status of a print job, used in conjunction with either gWoglp() or gWogldp(). The function gWoglst() can return the following values:
| 2 |
Could not find a default print device |
| 3 |
Job cancelled while printing |
status=gWoglpp(mode,devname,dlen,filename,flen,n,prop)
This nomination provides comprehensive control over the printer setup and printing of GINO output through OpenGL and the Windows printer interface. The additional arguments are:
mode
|
-2 |
Return current printer properties (returns status > 0) |
|
-1 |
Restore default printer properties and return them (returns status > 0) |
|
0 |
Open Printer Setup Window (returns status > 0) |
|
1 |
Restore default printer properties and print (same as gWogldp()) |
|
2 |
Open Printer Dialogue and print (same as gWoglp()) |
|
3 |
Print using current/default printer |
|
4 |
Print to BMP file (default = 800x600 pixels) |
|
5 |
Print to JPEG file (default = 800x600 pixels) |
|
6 |
Print to PNG file (default = 800x600 pixels) |
devname
Printer Device Name (input/output)
dlen
Length of devname (C/C++ only)
filename
Printer Output File name (in place of device) : used when PrinttoFile property = 1 in modes 2 and 3. If filename is blank when the PrinttoFile property is set, a file of the name <application>.prn is generated. Also used in mode 4,5,6 for metafile filename. In this mode, if the filename is blank <application>.bmp/jpg/png is generated as appropriate.
flen
Length of filename (C/C++ only)
n
Number of elements in prop array (rounded down to nearest even number)
prop
Integer array of pairs of <property> and <setting> (see table below). The setting values are used to change the current printer properties in modes 0, 2 and 3 but will be returned in all modes. Thus if prop contains the values: 7,2,1,2 the printer properties will be changed to landscape orientation and print 2 copies. If mode = -2 and prop contains the values: 2,0,8,0 the (device name,) paper size and print quality of the current printer will be returned. If prop[0]<=0 the first n/2 of the property flags and their values are returned.
| Property |
Property Description |
Settings |
| 1 |
No. of copies |
Number of copies |
| 2 |
Paper size
(see Windows print.h) |
= 1, Letter
= 5, Legal
= 9, A4
= 256, User defined |
| 3 |
Paper length |
Output length (in tenths of mm for printers or pixels for BMP files) |
| 4 |
Paper width |
Output width (in tenths of mm for printers or pixels for BMP files) |
| 5 |
Paper Source
(see Windows print.h) |
= 1, Default (Upper)
= 2, Lower
= 4, Manual
= 5, Envelope |
| 6 |
Scale Factor |
Scale/100 (ie 50 = half size) |
| 7 |
Orientation |
= 1, Portrait
= 2, Landscape |
| 8 |
DPI/Quality |
> 0, DPI
= -1, Draft
= -2, Low
= -3, Medium
= -4, High Quality |
| 9 |
Colour |
= 1, Monochrome
= 2, Colour |
| 10 |
Duplex |
= 1, Simple
= 2, Duplex
= 3, Vertical |
| 11 |
TTopt |
= 1, Bitmap
= 2, Download (HP printers)
= 3, Substitute (PostScript printers) |
| 20 |
PrinttoFile |
= -2, Disable and hide Print to File toggle
= -1, Disable Print to File toggle
= 0, Leave toggle as is (default)
= 1, Select toggle and use filename |
| 21 |
Metafile dpi |
= Nominal dots per inch for metafile creation |
| 22 |
JPEG Quality |
= 0-100, JPEG metafile quality (used for mode 5)
(default=75) |
status
Return Status
|
1 |
Print Cancelled or not required |
|
2 |
No default/current printer available |
If status > 0 the application should immediately call gCloseDevice() and re-nominate another GINO device (eg. gWogl() or gWoglw())
status=gWoglm(type,dpi,xres,yres,gFilename,gQuality)
This nomination routine is used to initialise GINO to be able to generate a metafile image containing an OpenGL scene. This is actually an interface to the gWoglpp routine (above), but provides a more intuitive argument list for the metafile initialisation.
type
Metafile type
|
GBMPFILE |
Uncompressed Windows Bitmap file (BMP) |
|
GJPEGFILE |
JPEG image format (JPG) |
|
GPNGFILE |
Portable Network Graphics file (PNG) |
dpi
Nominal metafile resolution.
xres, yres
Metafile image dimensions
gFilename
Optional output metafile file name. Default is <application>.<ext> where ext = bmp, jpg or png depending on the metafile type.
gQuality
Jpeg metafile quality (0-100). Default=75.
status
Return Status
|
0 |
Initialisation successful |
|
1 |
Metafile creation failed |
If status > 0 the application should immediately call gCloseDevice() and re-nominate another GINO device (eg. gWogl() or gWoglw())
gOglwin
This nomination routine is only used in GINOMENU applications, where graphics frames are required to display GINO graphics in a Windows OpenGL environment. Further details are found in the GINOMENU User Guide.
Window Size
If the gWogl() or gWoglw() routines have been used to nominate the device any changes the user of the application makes to the window size during operation will be handled by the driver. The driver will ensure that the picture is updated by redrawing from the backing store and scroll bars added to the window, if needed. However GINO is not able to take any further action until after gNewDrawing() is called. At this point the driver will resize the drawing limits to fit the window and these can be enquired by the application using the routine gEnqDrawingLimits() if the user wishes to re-scale the picture.
If the window size is changed by the user, this takes priority over the programmers request for a change through gSetDrawingLimits().
Double Buffering
By default, the Wogl driver will use a software double buffered pixel format for the display. This ensures the most consistent redrawing and refresh rates on any graphics card being used. For faster refresh rates, hardware double-buffering can be selected and this is achieved by setting the 'paper type' in the call to gSetDrawingLimits() to 0. However, there are instances, particularly where multiple GINO windows or frames are being used and where the graphics card is set to the highest acceleration setting, that areas of the window or frame are not updated or repaired when necessary. If problems are encountered, either reduce the hardware acceleration setting on the graphics card, using the Control Panel - Display - Settings - Advanced - Troubleshoot or revert back to the use of software double buffering.
Window Title
The default window title of a GINO application is a string composed of the GINO version and license owner. This can be superceded in the following order of precedence:
1) GINO config variable WOGLTITLE
2) System environment variable WOGLTITLE
3) Application call to gSetDeviceTitle()
Depth Buffer
The accuracy of hidden surface removal depends on the size of depth buffer in the OpenGL driver. By default this is set to be 32 bits (giving the highest quality output), but some graphics hardware will operate more efficiently using a smaller depth buffer (at the cost of lower quality output). The OPENGL32 DLL that is used by the WOGL driver always provides a 32bit option, but some hardware enhanced modes only work with 24bit or even 16bit depth buffers.
The default size of the depth buffer can be modified using the environment variable or GINO config variable, WOGLDEPTH.
Colour Palette
This driver only operates when windows is running in one of the 16bit, 24bit or 32bit colour modes (>256 colours). The driver is therefore always operating in direct mode (ndt=4), but an internal GINO palette with 1024 entries is still available. In this mode, gDefineRGB() can still be used but will have no effect on graphics already drawn.
Changes to colour 0 (the background colour) may not be seen unless followed by a call to gNewDrawing().
Thick Lines and Line Ends
The WOGL driver has been written to generate thick lines of all line-end types in 2D, but the only thick lines with no ends in 3D. OpenGL only provides thick lines with no ends and so those with square-ends and round-ends (in 2D) are generated by constructing a polygon of the required shape. The line-end type is ignored in 3D.
Fonts
The default font used by the WOGL driver is a fixed pitch, modern font using the system default character set which normally maps to ANSI Courier. Any of the Windows installed fonts may be selected using the routine gSetCharFontName(), with the available list obtained through the routine gEnqFontNameList(). In addition, the following list of registered fonts are available through the routine gSetCharFont() :
| 0 or 100 |
Courier (fixed-pitch) |
Alternative character/language sets may be selected using the routine gSetCharSet(). This usually only affects character codes > 128 as character codes 32-127 will always contain the ANSI character set.
Segment Facilities
The Windows OpenGL driver supports some of GINO's segment facilities in line with the OpenGL Display List facilities. Thus the following segment routines operate through this driver:
| gOpenSeg() |
Open segment (nseg = 1> (IMAX-1024)) |
Note that a segment must exist prior to making a reference to it using gInsertSegRef() and segments are always visible and hit sensitive.
N.B. As hardware fonts are stored internally as segments by the WOGL driver, any change to the current character/font settings will close the currently opened segment. Therefore it is essential that the required character/font attributes are set before a GINO segment is opened and are not altered within a segment.
Input Focus in Graphics Cursor Mode
When gGetCursorEvent() is called, the input focus of the device is set to be the graphics window. When the key has been pressed, the focus is returned to the previous window before gGetCursorEvent() was called. This operation is not supported when using the gWoglao() nomination routine.
Events
The following event types can be set through the routine gAddEventType(intype) where intype can be one of the following:
| GKEYPRESS |
Key or Mouse button press |
| GLOCATOR |
Screen position and Key/Mouse button press |
| GMOVEMENT |
Pointer/Mouse movement |
| GKEYRELEASE |
Key or Mouse button release |
| GMOUSEWHEEL |
Mouse wheel movement |
Multiple event types may be set concurrently. When the device has been nominated by gWogl() or gWoglw(), events are requested with the routine gWaitForEvent() with the resulting data for the event being returned through the routine gGetEventRecord() (see Advanced Interaction).
Information concerning events in conjunction with the gWoglao() nomination routine are described in the GUI programming environment section (see GUI Programming). Events are only supported if using the gWoglao() nomination routine with a window handle.
Cursor Types
All cursor types are windows resource cursors except GLARGECROSS which is a full window cross-hair cursor drawn in XOR mode. It uses the bakcol argument from gSetCursorType() to draw the cursor, so in order to operate correctly this value should not be set to 0.
Device Termination
When using either gWogl() or gWoglw(), the action at device termination is to halt GINO graphics and close the graphics window if gCloseDevice() has been called. If gSuspendDevice() has been called, the graphics window will remain on the screen and the program will pause at the call to gCloseGino(). The dialogue window will be closed at the same time as GINO is closed.
When using gWoglao(), at device termination it is the application programmers responsibility to release the bitmap device context.
Error Handling
When a GINO or other GINO library generates an error or warning message an error window is created and displayed at the bottom left of the screen. All subsequent error/warning messages are printed in this window. The user can alter the initial state of this window through the configuration variable NFERTR set in the configuration file GINO.CON as follows:
NFERTR
|
> 2 |
Errors are sent to a file "APPLICATION".ERR |
Window Visibility
The current graphics and dialogue windows can be made visible/invisible using the routines gSetGraphicsVis() and gSetDialogueVis():
| gSetGraphicsVis(gravis) |
Make graphics window visible/invisible |
| gSetDialogueVis(diavis) |
Make dialogue window visible/invisible |
where gravis & diavis can be either GINVISIBLE or GVISIBLE to hide or show the window.
The routine gSetGraphicsVis() will have no effect when the device has been nominated by using the gWoglao() routine. Calls to gSetDialogueVis() apply in all cases.
Application Icon
The GINO icon will be assigned to all windows created through these nomination routines. An application can replace this with one of their choosing by adding an icon resource of the name "GinoIcon" to their application. A typical resource file should contain the line:
GinoIcon ICON myapp.ico
where myapp.ico is the name of the user supplied application icon file.
Interacting with other Windows Applications
GINO graphics sent to the screen can be copied onto the Windows clipboard by pressing <ALT> <PRINT SCREEN>. Transfer of graphics to other applications via OLE or DDE is not supported.
Error Messages
The WINDOWS driver may at one time or another popup a message box. These messages are mainly informational, but may effect the drivers behaviour. The messages are described below:
UNABLE TO CREATE THE MESSAGE WINDOW
Sometimes when an application has been improperly closed the dialogue window will still exist in memory, although the dialogue window may not be visible. The WINDOWS driver will not be able to use this instance or create a new instance, hence there will not be a dialogue window. Reasons for this can be programs crashing or being terminated part way through (i.e. by a debugger). The only solution to this problem is to restart windows.
